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Abstract 


The Registration Data Access Protocol (RDAP) does not include capabilities to request partial 
responses. Servers will only return full responses that include all of the information that a client 
is authorized to receive. A partial response capability that limits the amount of information 
returned, especially in the case of search queries, could bring benefits to both clients and servers. 
This document describes an RDAP query extension that allows clients to specify their preference 
for obtaining a partial response. 


Status of This Memo 


This is an Internet Standards Track document. 


This document is a product of the Internet Engineering Task Force (IETF). It represents the 
consensus of the IETF community. It has received public review and has been approved for 
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1. Introduction 


The use of partial responses in RESTful API [REST] design is very common. The rationale is quite 
simple: instead of returning objects in API responses with all data fields, only a subset of the 
fields in each result object is returned. The benefit is obvious: less data transferred over the 
network means less bandwidth usage, faster server responses, less CPU time spent both on the 
server and the client, and less memory usage on the client. 
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Currently, RDAP does not provide a client with any way to request a partial response. Servers can 
only provide the client with a full response [RFC7483]. Servers cannot limit the amount of 
information returned in a response based on a client's preferences, and this creates 
inefficiencies. 


The protocol described in this specification extends RDAP search capabilities to enable partial 
responses through the provisioning of predefined sets of fields that clients can submit to an 
RDAP service by adding a new query parameter. The service is implemented using the Hypertext 
Transfer Protocol (HTTP) [RFC7230] and the conventions described in [RFC7480]. 


1.1. Conventions Used in This Document 


The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD 
NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and "OPTIONAL" in this document are to 
be interpreted as described in BCP 14 [RFC2119] [RFC8174] when, and only when, they appear in 
all capitals, as shown here. 


2. RDAP Path Segment Specification 


The path segment defined in this section is an OPTIONAL extension of search path segments 
defined in [RFC7482]. This document defines an RDAP query parameter, "fieldSet", whose value is 
a non-empty string identifying a server-defined set of fields returned in place of the full 
response. The field sets supported by a server are usually described in out-of-band documents 
(e.g., RDAP profile) together with other features. Moreover, this document defines in Section 2.1 
an in-band mechanism by means of which servers can provide clients with basic information 
about the supported field sets. 


The following is an example of an RDAP query including the "fieldSet" parameter: 


https://example.com/rdap/domains?name=example*.com&fieldSet=afieldset 


This solution can be implemented by RDAP providers with less effort than field selection and is 
easily requested by clients. The considerations that have led to this solution are described in 
more detail in Appendix A. 


2.1. Subsetting Metadata 


According to most advanced principles in REST design, collectively known as "Hypermedia as the 
Engine of Application State" (HATEOAS) [HATEOAS], a client entering a REST application through 
an initial URI should use server-provided links to dynamically discover available actions and 
access the resources it needs. In this way, the client is not required to have prior knowledge of 
the service nor, consequently, to hard-code the URIs of different resources. This allows the server 
to make URI changes as the API evolves without breaking clients. Definitively, a REST service 
should be as self-descriptive as possible. 
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Therefore, servers implementing the query parameter described in this specification SHOULD 
provide additional information in their responses about the available field sets. Such 
information is collected in a new JSON data structure named "subsetting_metadata" containing 
the following properties: 


"currentFieldSet": "String" (REQUIRED) 
either the value of the "fieldSet" parameter as specified in the query string, or the field set 
applied by default. 


"availableFieldSets": "AvailableFieldSet[]" (OPTIONAL) 
an array of objects, with each element describing an available field set. The AvailableFieldSet 
object includes the following members: 


"name": "String" (REQUIRED) 
the field set name. 


"default": "Boolean" (REQUIRED) 
indicator of whether the field set is applied by default. An RDAP server MUST define only 
one default field set. 


"description": "String" (OPTIONAL) 
a human-readable description of the field set. 


"links": "Link[]" (OPTIONAL) 
an array of links as described in [RFC8288] containing the query string that applies the 
field set (see Section 2.1.2). 
2.1.1. RDAP Conformance 
Servers returning the "subsetting_ metadata" section in their responses MUST include "subsetting" 
in the rdapConformance array. 
2.1.2. Representing Subsetting Links 


An RDAP server MAY use the "links" array of the "subsetting_metadata" element to provide ready- 
made references [RFC8288] to the available field sets (Figure 1). The target URI in each link is the 
reference to an alternative to the current view of results identified by the context URI. 


The "value", "rel", and "href" JSON values MUST be specified. All other JSON values are OPTIONAL. 
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"rdapConformance": [ 
"rdap_level_0", 
"subsetting" 


i 


"subsetting_metadata": 
"currentFieldSet": "afieldset", 
"availableFieldSets": [ 


"name": "anotherfieldset", 
"description": "Contains some fields", 
"default": false, 
Tk 
"value": "https://example.com/rdap/domains?name=example*.com 
&fieldSet=afieldset", 
"rel": "alternate", 
"href": "https://example.com/rdap/domains?name=example*.com 


&fieldSet=anotherfieldset", 
"title": "Result Subset Link", 
"type": "application/rdap+json" 


È 
X 


"domainSearchResults" : [ 


] 
} 


Figure 1: Example of a "subsetting_metadata" Instance 


3. Dealing with Relationships 


Representation of second-level objects within a field set produces additional considerations. 
Since the representation of the topmost returned objects will vary according to the field set in 
use, the response may contain no relationships (e.g., for an abbreviated field set) or may contain 
associated objects as in a normal RDAP query response. Each field set can indicate the format of 
the additional objects to be returned, in the same manner that the format of the topmost objects 
is controlled by the field set. 


4. Basic Field Sets 


This section defines three basic field sets that servers MAY implement to facilitate their 
interaction with clients: 
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"id": The server provides only the key field; "handle" for entities, and "IdhName" for domains 
and nameservers. If a returned domain or nameserver is an Internationalized Domain Name 
(IDN) [RFC5890], then the "unicodeName" field MUST additionally be included in the response. 
This field set could be used when the client wants to obtain a collection of object identifiers 
(Figure 2). 


"brief": The field set contains the fields that can be included in a "short" response. This field set 
could be used when the client is asking for a subset of the full response that provides only 
basic knowledge of each object. 


"full": The field set contains all of the information the server can provide for a particular object. 


The "objectClassName" field is implicitly included in each of the above field sets. RDAP providers 
SHOULD include a "links" field indicating the "self" link relationship. RDAP providers MAY also 
add any property providing service information. 


Fields included in the "brief" and "full" field set responses MUST take into account the user's 
access and authorization levels. 
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"rdapConformance": [ 
"rdap_level_0", 
"subsetting" 


l, 


"domainSearchResults": [ 


"objectClassName": "domain", 

"ldhName": "example1.com", 

Tiki? 2 || 
"value": "https://example.com/rdap/domain/example1.com", 
are TRES Alfa 
"href": "https://example.com/rdap/domain/example1.com", 


"type": "application/rdap+json" 


hi 
{ 
"objectClassName": "domain", 
"ldhName": "example2.com", 
"links": [ 
"value": "https://example.com/rdap/domain/example2.com", 
are lur “sels: 
"href": "https://example.com/rdap/domain/example2.com", 
"type": "application/rdap+json" 
] 


Figure 2: Example of RDAP Response According to the "id" Field Set 


5. Negative Answers 


Each request including an empty or unsupported "fieldSet" value MUST produce an HTTP 400 
(Bad Request) response code. Optionally, the response MAY include additional information 
regarding the supported field sets in the HTTP entity body (Figure 3). 
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{ 
"errorCode": 400, 
"title": "Field set 'unknownfieldset' is not valid", 
"description": [ 
"Supported field sets are: 'afieldset', 'anotherfieldset’." 
] 
} 


Figure 3: Example of RDAP Error Response Due to an Invalid Field Set Included in the Request 


6. IANA Considerations 


IANA has registered the following value in the "RDAP Extensions" registry: 


Extension identifier:  subsetting 

Registry operator: Any 

Published specification: RFC 8982 

Contact: JETF <iesg@ietf.org> 

Intended usage: This extension describes a best practice for partial response provisioning. 


7. Security Considerations 


A search query typically requires more server resources (such as memory, CPU cycles, and 
network bandwidth) when compared to a lookup query. This increases the risk of server 
resource exhaustion and subsequent denial of service. This risk can be mitigated by supporting 
the return of partial responses combined with other strategies (e.g., restricting search 
functionality, limiting the rate of search requests, and truncating and paging results). 


Support for partial responses gives RDAP operators the ability to implement data access control 
policies based on the HTTP authentication mechanisms described in [RFC7481]. RDAP operators 
can vary the information returned in RDAP responses based on a client's access and 
authorization levels. For example: 


e the list of fields for each set can differ based on the client's access and authorization levels; 


e the set of available field sets could be restricted based on the client's access and 
authorization levels. 


Servers can also define different result limits according to the available field sets, so a more 
flexible truncation strategy can be implemented. The new query parameter presented in this 
document provides RDAP operators with a way to implement a server that reduces inefficiency 
risks. 
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Appendix A. Approaches to Partial Response Implementation 


Looking at the implementation experiences of partial responses offered by data providers on the 
web, two approaches are observed: 


e the client explicitly describes the data fields to be returned; 
e the client describes a name identifying a server-defined set of data fields. 


The former is more flexible than the latter because clients can specify all the data fields they 
need. However, it has some drawbacks: 


e Fields have to be declared according to a given syntax. This is a simple task when the data 
structure of the object is flat, but it is much more difficult when the object has a tree 
structure like that of a JSON object. The presence of arrays and deep nested objects 
complicate both the syntax definition of the query and, consequently, the processing 
required on the server side. 


e Clients need to recognize the returned data structure to avoid cases when the requested 
fields are invalid. 


e The request of some fields might not match the client's access and authorization levels. 
Clients might request unauthorized fields, and servers have to define a strategy for 
responding such as always returning an error response or returning a response that ignores 
the unauthorized fields. 


A.1. Specific Issues Raised by RDAP 


In addition to those listed above, RDAP responses raise some specific issues: 


e Relevant entity object information is included in a jCard, but such information cannot be 
easily selected because it is split into the items of a jagged array. 


e RDAP responses contain some properties providing service information (e.g., 
rdapConformance, links, notices, remarks, etc.), which are not normally selected but are just 
as important. They could be returned anyway but, in this case, the server would provide 
unrequested data. 


It is possible to address these issues. For example, the Catnap Query Language [CQL] is a 
comprehensive expression language that can be used to customize the JSON response of a 
RESTful web service. Application of CQL to RDAP responses would explicitly identify the output 
fields that would be acceptable when a few fields are requested but it would become very 
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complicated when processing a larger number of fields. In the following, two CQL expressions 
for a domain search query are shown (Figure 4). In the first, only objectClassName and ldhName 
are requested. In the second, the fields of a possible WHOIS-like response are listed. 


https://example.com/rdap/domains?name=example*.com 
&fields=domainSearchResults(objectClassName, 1dhName) 


https://example.com/rdap/domains?name=example*.com 
&fields=domainSearchResults(objectClassName, 1dhName, 
unicodeName, 
status, 
events(eventAction,eventDate), 
entities(objectClassName, handle, roles), 
nameservers(objectClassName, ldhName) ) 


Figure 4: Examples of CQL Expressions for a Domain Search Query 


The field set approach seems to facilitate RDAP interoperability. Servers can define basic field 
sets that, if known to clients, can increase the probability of obtaining a valid response. The 
usage of field sets makes the query string less complex. Moreover, the definition of predefined 
sets of fields makes it easier to establish result limits. 


Finally, considering that there is no real need for RDAP users to have the maximum flexibility in 
defining all the possible sets of logically connected fields (e.g., users interested in domains 
usually need to know the status, the creation date, and the expiry date of each domain), the field 
set approach is preferred. 
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